
/*
 * Copyright 2002-2022 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/*
 *版权所有2002-2022原作者。
 *
 *根据Apache许可证2.0版（“许可证”）获得许可；
 *除非符合许可证，否则不得使用此文件。
 *您可以在以下地址获取许可证副本：
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 *除非适用法律要求或书面同意，软件
 *根据许可证分发的内容是按“原样”分发的，
 *无任何明示或暗示的保证或条件。
 *有关管理权限和
 *许可证下的限制。
 */

package org.springframework.beans.factory.config;

import java.util.Iterator;

import org.springframework.beans.BeansException;
import org.springframework.beans.factory.ListableBeanFactory;
import org.springframework.beans.factory.NoSuchBeanDefinitionException;
import org.springframework.lang.Nullable;

/**
 * Configuration interface to be implemented by most listable bean factories.
 * In addition to {@link ConfigurableBeanFactory}, it provides facilities to
 * analyze and modify bean definitions, and to pre-instantiate singletons.
 *
 * <p>This subinterface of {@link org.springframework.beans.factory.BeanFactory}
 * is not meant to be used in normal application code: Stick to
 * {@link org.springframework.beans.factory.BeanFactory} or
 * {@link org.springframework.beans.factory.ListableBeanFactory} for typical
 * use cases. This interface is just meant to allow for framework-internal
 * plug'n'play even when needing access to bean factory configuration methods.
 *
 * @author Juergen Hoeller
 * @since 03.11.2003
 * @see org.springframework.context.support.AbstractApplicationContext#getBeanFactory()
 */
/**
 *大多数可列表bean工厂要实现的配置接口。
 *除了｛@link ConfigurationBeanFactory｝之外，它还提供了
 *分析和修改bean定义，并预实例化单例。
 *
 *＜p＞｛@link.org.springframework.beans.factory.BeanFactory｝的子接口
 *不应在正常应用程序代码中使用：坚持
 *｛@link org.springframework.beans.factory.BeanFactory｝或
 *｛@link org.springframework.beans.factory.ListableBeanFactory｝
 *使用案例。此接口仅用于允许框架内部
 *即使在需要访问bean工厂配置方法的情况下，插件也会显示。
 *
 *@作者Juergen Hoeller
 *@自2003年11月3日
 *@see org.springframework.context.support.AbstractApplicationContext#getBeanFactory（）
 */
public interface ConfigurableListableBeanFactory
		extends ListableBeanFactory, AutowireCapableBeanFactory, ConfigurableBeanFactory {

	/**
	 * Ignore the given dependency type for autowiring:
	 * for example, String. Default is none.
	 * @param type the dependency type to ignore
	 */
	/**
	 *忽略自动布线的给定依赖类型：
	 *例如String。默认值为“无”。
	 *@param键入要忽略的依赖项类型
	 */
	void ignoreDependencyType(Class<?> type);

	/**
	 * Ignore the given dependency interface for autowiring.
	 * <p>This will typically be used by application contexts to register
	 * dependencies that are resolved in other ways, like BeanFactory through
	 * BeanFactoryAware or ApplicationContext through ApplicationContextAware.
	 * <p>By default, only the BeanFactoryAware interface is ignored.
	 * For further types to ignore, invoke this method for each type.
	 * @param ifc the dependency interface to ignore
	 * @see org.springframework.beans.factory.BeanFactoryAware
	 * @see org.springframework.context.ApplicationContextAware
	 */
	/**
	 *忽略自动布线的给定依赖接口。
	 *＜p＞这通常由应用程序上下文用于注册
	 *通过其他方式解析的依赖项，如BeanFactory
	 *通过ApplicationContextAware创建BeanFactoryAware或ApplicationContext。
	 *＜p＞默认情况下，仅忽略BeanFactoryAware接口。
	 *对于要忽略的其他类型，请为每个类型调用此方法。
	 *@param ifc要忽略的依赖项接口
	 *@参见org.springframework.beans.factory.BeanFactory软件
	 *@参见org.springframework.context.ApplicationContextAware
	 */
	void ignoreDependencyInterface(Class<?> ifc);

	/**
	 * Register a special dependency type with corresponding autowired value.
	 * <p>This is intended for factory/context references that are supposed
	 * to be autowirable but are not defined as beans in the factory:
	 * e.g. a dependency of type ApplicationContext resolved to the
	 * ApplicationContext instance that the bean is living in.
	 * <p>Note: There are no such default types registered in a plain BeanFactory,
	 * not even for the BeanFactory interface itself.
	 * @param dependencyType the dependency type to register. This will typically
	 * be a base interface such as BeanFactory, with extensions of it resolved
	 * as well if declared as an autowiring dependency (e.g. ListableBeanFactory),
	 * as long as the given value actually implements the extended interface.
	 * @param autowiredValue the corresponding autowired value. This may also be an
	 * implementation of the {@link org.springframework.beans.factory.ObjectFactory}
	 * interface, which allows for lazy resolution of the actual target value.
	 */
	/**
	 *使用相应的自动连线值注册特殊依赖项类型。
	 *＜p＞这是用于假定的工厂/上下文引用
	 *可自动布线，但在工厂中未定义为bean：
	 *例如，ApplicationContext类型的依赖项解析为
	 *bean所在的ApplicationContext实例。
	 *＜p＞注意：在普通BeanFactory中没有注册这样的默认类型，
	 *甚至连BeanFactory接口本身都没有。
	 *@param dependencyType要注册的依赖类型。这通常会
	 *是一个基本接口，如BeanFactory，并解析其扩展
	 *以及如果声明为自动布线依赖项（例如ListableBeanFactory），
	 *只要给定值实际上实现了扩展接口。
	 *@param autowiredValue对应的自动连线值。这也可能是
	 *｛@linkorg.springframework.beans.factory.ObjectFactory｝的实现
	 *接口，允许延迟解析实际目标值。
	 */
	void registerResolvableDependency(Class<?> dependencyType, @Nullable Object autowiredValue);

	/**
	 * Determine whether the specified bean qualifies as an autowire candidate,
	 * to be injected into other beans which declare a dependency of matching type.
	 * <p>This method checks ancestor factories as well.
	 * @param beanName the name of the bean to check
	 * @param descriptor the descriptor of the dependency to resolve
	 * @return whether the bean should be considered as autowire candidate
	 * @throws NoSuchBeanDefinitionException if there is no bean with the given name
	 */
	/**
	 *确定指定的bean是否符合自动连线候选，
	 *被注入到声明匹配类型依赖关系的其他bean中。
	 *＜p＞此方法还检查祖先工厂。
	 *@param beanName要检查的bean的名称
	 *@param descriptor要解析的依赖项的描述符
	 *@return是否应将bean视为autowire候选
	 *如果没有具有给定名称的bean，@throws NoSuchBeanDefinitionException
	 */
	boolean isAutowireCandidate(String beanName, DependencyDescriptor descriptor)
			throws NoSuchBeanDefinitionException;

	/**
	 * Return the registered BeanDefinition for the specified bean, allowing access
	 * to its property values and constructor argument value (which can be
	 * modified during bean factory post-processing).
	 * <p>A returned BeanDefinition object should not be a copy but the original
	 * definition object as registered in the factory. This means that it should
	 * be castable to a more specific implementation type, if necessary.
	 * <p><b>NOTE:</b> This method does <i>not</i> consider ancestor factories.
	 * It is only meant for accessing local bean definitions of this factory.
	 * @param beanName the name of the bean
	 * @return the registered BeanDefinition
	 * @throws NoSuchBeanDefinitionException if there is no bean with the given name
	 * defined in this factory
	 */
	/**
	 *返回指定bean的注册BeanDefinition，允许访问
	 *属性值和构造函数参数值（可以是
	 *在bean工厂后处理期间修改）。
	 *＜p＞返回的BeanDefinition对象不应是副本，而应是原始对象
	 *工厂中注册的定义对象。这意味着它应该
	 *如果需要，可以将其转换为更具体的实现类型。
	 *<p><b>注意：</b>此方法不考虑祖先工厂。
	 *它只用于访问此工厂的本地bean定义。
	 *@param beanName bean的名称
	 *@return注册的BeanDefinition
	 *如果没有具有给定名称的bean，@throws NoSuchBeanDefinitionException
	 *在此工厂中定义
	 */
	BeanDefinition getBeanDefinition(String beanName) throws NoSuchBeanDefinitionException;

	/**
	 * Return a unified view over all bean names managed by this factory.
	 * <p>Includes bean definition names as well as names of manually registered
	 * singleton instances, with bean definition names consistently coming first,
	 * analogous to how type/annotation specific retrieval of bean names works.
	 * @return the composite iterator for the bean names view
	 * @since 4.1.2
	 * @see #containsBeanDefinition
	 * @see #registerSingleton
	 * @see #getBeanNamesForType
	 * @see #getBeanNamesForAnnotation
	 */
	/**
	 *返回此工厂管理的所有bean名称的统一视图。
	 *＜p＞包括bean定义名称以及手动注册的名称
	 *单例实例，bean定义名称始终排在第一位，
	 *类似于bean名称的类型/注释特定检索的工作方式。
	 *@return bean名称视图的复合迭代器
	 *@自4.1.2
	 *@参见#containsBeanDefinition
	 *@参见#registerSingleton
	 *@参见#getBeanNameForType
	 *@参见#getBeanNameForAnnotation
	 */
	Iterator<String> getBeanNamesIterator();

	/**
	 * Clear the merged bean definition cache, removing entries for beans
	 * which are not considered eligible for full metadata caching yet.
	 * <p>Typically triggered after changes to the original bean definitions,
	 * e.g. after applying a {@link BeanFactoryPostProcessor}. Note that metadata
	 * for beans which have already been created at this point will be kept around.
	 * @since 4.2
	 * @see #getBeanDefinition
	 * @see #getMergedBeanDefinition
	 */
	/**
	 *清除合并的bean定义缓存，删除bean的条目
	 *它们还不被认为符合完整元数据缓存的条件。
	 *＜p＞通常在更改原始bean定义后触发，
	 *例如在应用{@link BeanFactoryPostProcessor}之后。注意元数据
	 *对于此时已经创建的bean，将保留。
	 *@自4.2
	 *@参见#getBeanDefinition
	 *@参见#getMergedBeanDefinition
	 */
	void clearMetadataCache();

	/**
	 * Freeze all bean definitions, signalling that the registered bean definitions
	 * will not be modified or post-processed any further.
	 * <p>This allows the factory to aggressively cache bean definition metadata
	 * going forward, after clearing the initial temporary metadata cache.
	 * @see #clearMetadataCache()
	 * @see #isConfigurationFrozen()
	 */
	/**
	 *冻结所有bean定义，表明已注册的bean定义
	 *将不会被进一步修改或后处理。
	 *＜p＞这允许工厂积极缓存bean定义元数据
	 *在清除初始临时元数据缓存之后继续。
	 *@参见#clearMetadataCache（）
	 *@参见#isConfigurationFrozen（）
	 */
	void freezeConfiguration();

	/**
	 * Return whether this factory's bean definitions are frozen,
	 * i.e. are not supposed to be modified or post-processed any further.
	 * @return {@code true} if the factory's configuration is considered frozen
	 * @see #freezeConfiguration()
	 */
	/**
	 *返回此工厂的bean定义是否已冻结，
	 *即不应被进一步修改或后处理。
	 *如果工厂的配置被认为是冻结的，则@return｛@code true｝
	 *@参见#冷冻配置（）
	 */
	boolean isConfigurationFrozen();

	/**
	 * Ensure that all non-lazy-init singletons are instantiated, also considering
	 * {@link org.springframework.beans.factory.FactoryBean FactoryBeans}.
	 * Typically invoked at the end of factory setup, if desired.
	 * @throws BeansException if one of the singleton beans could not be created.
	 * Note: This may have left the factory with some beans already initialized!
	 * Call {@link #destroySingletons()} for full cleanup in this case.
	 * @see #destroySingletons()
	 */
	/**
	 *确保实例化所有非惰性init单例，同时考虑
	 *｛@link org.springframework.beans.factory.FactoryBean FactoryBean｝。
	 *如果需要，通常在工厂设置结束时调用。
	 *如果无法创建一个单例bean，@throws BeansException。
	 *注意：这可能已经离开工厂，一些bean已经初始化！
	 *在这种情况下，调用｛@link#destroySingletons（）｝进行完全清理。
	 *@参见#destroySingletons（）
	 */
	void preInstantiateSingletons() throws BeansException;

}
